Short:    V1.20 powerful Join replacement
Author:   stoecker@epost.de (Dirk Stoecker)
Uploader: stoecker@epost.de (Dirk Stoecker)
Version:  1.20
Type:     util/sys
Kurz:     Join Ersatz mit vielen Funktionen

Advantages of this Join:
  - it can be called like original Join - complete replacement
  - it can take the filenames from a filelist
  - it can built the filenames out of a file-splitter name description
  - it supports patterns
  - it can add the files to an existing source (useful when low diskspace)
  - it is able to delete source-files when needed
  - it has a lot of text join options (AMIGAGUIDE, HEADER, NAMEHEADER)
  - it is in the Public Domain (including sources)
  - it is really fast
  - it also works with low memory, but is slower then
  - it can be started from Workbench as well as from CLI

Join needs OS 37 (2.0) or later OS versions!
Of course this Join is reentrant (pure bit) like the original one.

There is one main difference between my and original Join: My Join brings
output. When you do not like that, use QUIET option to turn it off.

On workbench start you only need to specify normal CLI command line as
tooltype. All tooltypes of program icon (when exists) or project icons
are scanned and used. When an error occurs, the left tooltypes are not
scanned! In the Icons directory of this archive are one program and one
project icon as examples.

USAGE:
  Join FILE/M,AS=TO/K/A,FILELIST/K,SPLITTED/K,PAT=PATTERN/K,OUTPUT/K,
       AG=AMIGAGUIDE/S,HEADER/S,NAMEHEADER/S,ADD/S,DEL=DELSOURCE/S,
       QUIET/S,ALL/S,NOPAT=NOPATTERN/S:
  FILE       files, which should be joined
  AS=TO	     destination file
  FILELIST   takes the filenames out of a file (every line contains
             a complete filename)
  SPLITTED   allows joining splitted files, data has to look like:
             <filename>[,<first number>[,<last number>]], filename has
             to hold ONE format string like %ld,%03ld,%lx,%2lx,
             numbers have to be decimal

  PATTERN    gives a pattern the filename must match
  OUTPUT     specifies output path

  AMIGAGUIDE at the start of every file @node "filename" and at the
             end @endnode is inserted
  HEADER     /* ======== ... ========= */ is inserted at filestart
  NAMEHEADER /* ===... filename ...=== */ is inserted at filestart
  ADD        adds the files to an existing destination file
  DELSOURCE  deletes the sourcefiles
  QUIET      brings no output
  ALL        scan into directories
  NOPATTERN  take names as given

There are three modes:
1) FILE - This mode joins files, which are given in command line. Standard
Join does this always. The files are joined in the way they are given.

Example: Join xaa xab xac xad xae TO Archiv.lha

2) FILELIST - Equals FILE mode, but the filenames are in a file, which
may be specified after FILELIST keyword. In the filelist the must be one
filename per line.

Example: Join FILELIST JoinList TO Archiv.lha
[Where JoinList ist a file like that:
xaa
xab
xac
xad
xae
]

Such filelists may for example be generated with List command:
 List <pattern> >RAM:filelist NOHEAD QUICK
or
 List <pattern> >RAM:filelist LFORMAT "%s"

Later on you may sort it with Sort RAM:filelist RAM:filelist

3) SPLITTED - This mode is used, when joining splitted files. The string
passed with SPLITTED keyword contains of 3 parts:

- file-name of splitted files including place-holders for numbers:
   Archiv.%03ld   describes files named Archiv.000, Archiv.001, Archiv.010
   Archiv.%ld     describes files named Archiv.0, Archiv.1, Archiv.2

  Allowed place holders are %lx, %ld, %lu, %lc (not very useful). See
  RawDoFmt or printf documentation to find out, what they and the format
  flags (%03ld, %3ld, %-3ld) do.

- After the filename you may specify the number, where the splitted files
  start. This is optional, the default is 0. The filename and the number
  are seperated by a ','.

- The last part is the number, where the list ends. This is optional too.
  At default Join finishs, when it could not load a file. When the last
  number is given, missing files are skipped instead. You need to specify
  first number always, when defining end number. The numbers are seperated
  by ',' again.

Example: There are files f0, f1, f2, f3, f5, f9, f10

Join f%ld,1,10 TO f   joins files f1 f2 f3 f5 f9, f10 to file f
                      (f4, f6, f7, f8 are skipped)

Join f%ld,2 TO f      joins files f2 f3 to file f
                      (f4 is missing -> end)

Join f%ld TO f        joins file f0 f1 f2 f3 to f

Additional to these three modes, there are some goodies:

- PATTERN allows to specify a special pattern, the filenames should match.
  This is useful sometimes, when patterns cannot be described with normal
  filename.
  Example: join all text files on a device including sub directories.
    Join #? ALL TO AllTexts PATTERN #?.TXT
- OUTPUT lets you specify any standard Amiga file for output (f.e. "RAM:Out"
  or "CON:0/0/640/200/JoinOutput/AUTO/WAIT/CLOSE"). This is most useful for
  Workbench use.

- AMIGAGUIDE allows to insert at start of every file @node "filename" and
  at the end @endnode. This gives you a file, where all joined files are
  Amigaguide nodes.
- HEADER inserts /* ======== ... ========= */ as seperation between the
  files.
- NAMEHEADER inserts /* ===... filename ...=== */ before every joined file.
- ADD adds the files to an existing destination file.
- DELSOURCE deletes the sourcefiles after they are joined.
- QUIET suppresses output. Join is completely silent with that keyword.
- ALL allows to scan into directories, when filenames contain patterns.
- NOPATTERN turns of pattern matching. This may be useful, when filenames
  already contain patterns.

Note: Pattern matching works for all three modes!

This program is in the public domain. Use it as you want, but WITHOUT ANY
WARRANTY!

Please report me bugs, comments, suggestions and problems. If possible
write a little mail if you use the program sometimes. If there are some
Enforcer hits or other problems report them as good as possible.

Please contact me:

*********************************************************************
* snail-mail:                  * e-mail:                            *
*   Dirk Stoecker              *   stoecker@epost.de                *
*   Geschwister-Scholl-Str. 10 *   dirk@dstoecker.de                *
*   01877 Bischofswerda        * world wide web:                    *
*   GERMANY                    *   http://www.dstoecker.de/         *
* phone:                       * pgp key:                           *
*   GERMANY +49 (0)3594/706666 *   get from WWW pages or keyservers *
*********************************************************************

Following is my PGP signature for the corresponding LhA-File.
Use ' pgpv JoinReplace.readme -o JoinReplace.lha ' to check it.
Key fingerprint: B9 F2 3A 1A 29 02 75 16  6A C6 5B 7D 5E F6 16 CF.
All my releases after April 2001 have a PGP signature with this key.
Be alarmed if signature is missing or wrong.

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 5.0i for non-commercial use
MessageID: YglhZqAA19jnGStGcGjv9oURHwf85kxD

iQCVAwUAO07EebOTsAT/iOY9AQF0QAP+P0C3eJylhYHJCquIRHEOZn+XBVdgPtYV
jRFSNgNx4NQbjopgTBg/vPBdWcGAK/LhNr620wdS8g0p28O2WrZgw5b0R7FUwoAO
nch1JNxUTEexAL7OarErW24SEc8+lIq3G7n3232xWlQ4Wbny558v4+KsL1vw844v
SRvB+tnTpyw=
=QkMP
-----END PGP SIGNATURE-----


============================= Archive contents =============================

Original  Packed Ratio    Date     Time    Name
-------- ------- ----- --------- --------  -------------
    2146    1523 29.0% 13-Jul-01 11:50:24  JoinReplace.info
     628     263 58.1% 13-Jul-01 11:50:24 +Icons.info
     862     317 63.2% 13-Jul-01 11:50:24 +Join.info
     871     328 62.3% 13-Jul-01 11:50:24 +JoinProjekt.info
    4664    2927 37.2% 13-Jul-01 11:50:24 +Join
    6720    2796 58.3% 13-Jul-01 11:50:24 +JoinReplace.readme
    2188     805 63.2% 13-Jul-01 11:50:24 +SDI_ASM_STD_functions.lib
    5603    1970 64.8% 13-Jul-01 11:50:24 +SDI_ASM_STD_protos.h
    1257     550 56.2% 13-Jul-01 11:50:24 +SDI_version.h
   14299    4864 65.9% 13-Jul-01 11:50:24 +Join.c
     354     238 32.7% 13-Jul-01 11:50:24 +SMakeFile
-------- ------- ----- --------- --------
   39592   16581 58.1% 16-Jul-101 20:00:14   11 files
